<h2>DESCRIPTION</h2>

<em>r.reclass</em> creates an <em>output</em> map layer
based on an <em>input</em> integer raster map layer.  The output
map layer will be a reclassification of the input map layer
based on reclass rules input to <em>r.reclass</em>, and can
be treated in much the same way that raster maps are
treated.  A <em>TITLE</em> for the output map layer may be
(optionally) specified by the user.

<p>The reclass rules are read from standard input (i.e., from
the keyboard, redirected from a file, or piped through
another program).

<p>Before using <em>r.reclass</em> the user must know the following:

<ol>
<li>The new categories desired;  and, which old categories fit into 
which new categories.
<li>The names of the new categories.
</ol>

<h2>NOTES</h2>

In fact, the <em>r.reclass</em> program does <em>not</em> generate any new
raster map layers (in the interests of disk space conservation).  Instead, a
<b>reclass table</b> is stored which will be used to reclassify the
original raster map layer each time the new (reclassed) map name
is requested.  As far as the user (and programmer) is concerned, that
raster map has been created.

<p><em>r.reclass</em> only works on an <i>integer</i> input raster map; if the
input map is instead floating point data, you must multiply the input data by some
factor to achieve whole number input data, otherwise <em>r.reclass</em> will round
the raster values down to the next integer.

<p>Also note that although the user can generate a <em>r.reclass</em> map
which is based on another <em>r.reclass</em> map,
the new <em>r.reclass</em> map will be stored in GRASS as a reclass
of the <em>original</em> raster map on which the first reclassed map was
based.  Therefore, while GRASS allows the user to provide <em>r.reclass</em> 
map layer information which is based on an already reclassified map
(for the user's convenience), no <em>r.reclass</em> map layer
(i.e., <em>reclass table</em>) will ever be <em>stored</em>
as a <em>r.reclass</em> of a <em>r.reclass</em>.

<p>To convert a reclass map to a regular raster map layer, set your
geographic region settings to match the settings in the header for the
reclass map (with "<tt>g.region&nbsp;raster=reclass_map</tt>", or
viewable by running <em><a href="r.info.html">r.info</a></em>) 
and then run <em><a href="r.resample.html">r.resample</a></em>.

<p><em><a href="r.mapcalc.html">r.mapcalc</a></em> can be used to convert
a reclass map to a regular raster map layer as well:

<div class="code"><pre>
  r.mapcalc "raster_map = reclass_map"
</pre></div>


<p>where <em>raster_map</em> is the name to be given to the new raster map,
and <em>reclass_map</em> is an existing reclass map.

<p>Because <em>r.reclass</em> generates internally simply a table by
referencing some original raster map layer rather than creating a full
new reclassed raster map layer, a <em>r.reclass</em> map layer will
no longer be accessible if the original raster map layer, upon which
it was based, is later removed. Therefore, attempting to remove a
raster map layer from which a <em>r.reclass</em> has been derived
is only possible if the original map is removed first.
Alternatively, a <em>r.reclass</em> map can be removed including 
its base map by using <p><em><a href="g.remove.html">g.remove</a></em>'s
<b>-b</b> flag.

<p>A <em>r.reclass</em> map is not a true raster map layer.
Rather, it is a table of reclassification values which reference the
input raster map layer.  Therefore, users who wish to retain reclassified
map layers must also save the original input raster map layers
from which they were generated. Alternatively <em>r.recode</em> can be used.

<p>Category values which are not explicitly reclassified to a new value
by the user will be reclassified to NULL.


<h3>Reclass Rules</h3>

Each line of input must have the following format:

<dl>
<dd><b>input_categories=</b><em>output_category  </em>[<em>label</em>]
</dl>

<p>where each line of input specifies the category values in the
input raster map layer to be reclassified to the new
<em>output_category</em> category value.  Specification of
a <em>label</em> to be associated with the new output map
layer category is optional.  If specified, it is recorded
as the category label for the new category value.  The
equal sign = is required.  The <em>input_category(ies)</em>
may consist of single category values or a range of such
values in the format "<em>low</em> thru <em>high</em>." The
word "thru" must be present.
<p>To include all (remaining) values the asterix "*" can be used. This
rule has to be set as last rule. No further rules are accepted after
setting this rule. The special rule "<tt>* = *</tt>" specifies
that all categories not expicitly set by one of the above rules
should be passed through unaltered instead of being set to NULL.
<p>Categories to become no data are specified by setting the output
category value to "<tt>NULL</tt>".
<p>
A line containing only the word <b>end</b> terminates the
input.


<h2>EXAMPLES</h2>

<h3>Reclass rules examples</h3>

The following examples may help clarify the reclass rules.

<p>
The first example reclassifies categories 1, 2 and 3 in the input raster
map layer "roads" to category 1 with category label "good quality" in the output map
layer, and reclassifies input raster map layer categories 4 and 5 to
category 2 with the label "poor quality" in the output map layer.

<div class="code"><pre>
    1 2 3   = 1    good quality
    4 5     = 2    poor quality
</pre></div>

<p>
The following example reclassifies categories 1, 3 and 5 in the input raster
map layer to category 1 with category label "poor quality" in the output
map layer, and reclassifies input raster map layer categories 2, 4, and 6
to category 2 with the label "good quality" in the output map layer.
All other values are reclassified to NULL.
<div class="code"><pre>
    1 3 5   = 1    poor quality
    2 4 6   = 2    good quality
    *       = NULL
</pre></div>

<p>
The following example reclassifies input raster map layer categories
1 thru 10 to output 
map layer category 1, input map layer categories 11 thru 20 to output map layer
category 2, and input map layer categories 21 thru 30 to output map layer
category 3, all without labels. The range from 30 to 40 is reclassified as
NULL.
<div class="code"><pre>
     1 thru 10	= 1
    11 thru 20	= 2
    21 thru 30	= 3
    30 thru 40  = NULL
</pre></div>

<p>
The following example shows overlapping rules. Subsequent rules override
previous rules. Therefore, the below example
reclassifies input raster map layer categories 1 thru 19 and 51 thru 100
to category 1 in the output map layer,
input raster map layer categories 20 thru 24 and 26 thru 50 to
the output map layer category 2, and input raster map layer category 25
to the output category 3.
<div class="code"><pre>
     1 thru 100	= 1    poor quality
    20 thru 50	= 2    medium quality
    25	        = 3    good quality
</pre></div>

<p>
The previous example could also have been entered as:
<div class="code"><pre>
     1 thru 19  51 thru 100	= 1    poor quality
    20 thru 24  26 thru 50	= 2    medium quality
    25				= 3    good quality
</pre></div>
or as:
<div class="code"><pre>
     1 thru 19	 = 1    poor quality
    51 thru 100	 = 1
    20 thru 24	 = 2
    26 thru 50	 = 2    medium quality
    25		 = 3    good quality
</pre></div>

<p>
The final example was given to show how the labels are handled.  If a new
category value appears in more than one rule (as is the case with new 
category values 1 and 2),
the last label which was specified becomes the label for that category.
In this case the labels are assigned exactly as in the two previous examples.


<h3>Usage example</h3>

In this example, the 21 classes of the landuse map (North Carolina sample
dataset) are simplified to 7 classes:

<div class="code"><pre>
r.category landuse96_28m
0	not classified
1	High Intensity Developed
2	Low Intensity Developed
3	Cultivated
[...]
20	Water Bodies
21      Unconsolidated Sediment

# use this command or save rules with editor in textfile "landuserecl.txt"
echo "0 = NULL
1 2     = 1 developed
3       = 2 agriculture
4 6     = 3 herbaceous
7 8 9   = 4 shrubland
10 thru 18 = 5 forest
20      = 6 water
21      = 7 sediment" &gt; landuserecl.txt

r.reclass input=landuse96_28m output=landclass96_recl \
  rules=landuserecl.txt \
  title="Simplified landuse classes 1996"

# verify result
r.category landuse96_recl
1	developed
2	agriculture
3	herbaceous
4	shrubland
5	forest
6	water
7	sediment
</pre></div>

<h2>SEE ALSO</h2>

<em>
<a href="r.recode.html">r.recode</a>,
<a href="r.resample.html">r.resample</a>,
<a href="r.rescale.html">r.rescale</a>
</em>


<h2>AUTHORS</h2>

James Westervelt,<br>
Michael Shapiro<br>
U.S.Army Construction Engineering Research Laboratory

<!--
<p>
<i>Last changed: $Date$</i>
-->
